List boxes are a mechanism that lets the user make a selection from multiple choices. Where this interface differs from radio buttons, is that the user can optionally make multiple selections from the list, and the available choices are dynamic. The box’s dimensions are defined by your application. However, a 1-pixel border is drawn just outside these co-ordinates, and a scroll bar is automatically installed to the right of the list box, thereby consuming an additional 16 pixels. Once a list box is created, your application can define each line of text within the list box. Lines can be added, changed and deleted as required.
Various selection rules can be put into place to control how the user can select lines. The simplest allows only one line to be selected at a time. More complex methods allow multiple lines to be selected with various limitations imposed. When a line (or lines) is selected, it is highlighted. When a user clicks or double-clicks a line, Tools Plus reports this to your application with a doListBox event (your application may choose to ignore double-clicks). Although your application can create blank lines in a list box, they can’t be selected by the user.
List boxes are created on the current window by the NewListBox procedure. Each list box is referenced by a unique list box number that can be from 1 to 255. This number is specified when the list box is created, and refers to the specific list box until that list box is deleted. Note that the list box number is related to its associated window. This means that two different windows can each have a list box numbered “1” without interfering with each other. Whenever the user clicks on a line within the list box, PollSystem reports this to your application.
After NewListBox creates an empty list box, repeated calls to SetListBoxText will append lines to the list box, or replace an existing line’s text with new text. The GetListBoxText procedure is used to obtain any line’s text. Individual lines are referenced by a relative line number, where the top line is line 1, the second from the top is line 2, and so on. All lines are referenced by the relative line number, even when lines are inserted or deleted.
The InsertListBoxLine procedure inserts a new line between two existing lines. The DeleteListBoxLine procedure deletes an existing line. In both cases, if any other lines were selected before calling the procedure, they retain their selection status.
SetListBoxLine is used to highlight a line, and is often used to set a default line the first time a list box is displayed. The first selected line is automatically scrolled into view. GetListBoxLine is a complimentary function that tells you if a specific line is selected or not. An additional function, GetListBoxLines (ending with an “s”) is used to determine the next selected line. This is useful when the selection of multiple lines is allowed because your application does not have to query each line individually.
Lines in a list box can be arranged in alphabetical order by adding or inserting lines in the correct place. The SearchListBox function tells you where to insert a new text line to make the list alphabetic.
One additional procedure is used to make your list boxes look professional: DrawListBox. Because list boxes are “live,” the use of SetListBoxText, SetListBoxLine, InsertListBoxLine, and DeleteListBoxLine has an immediate and visible affect on your list. This can become quite unsightly when adding one line at a time to a list box of any significant length. DrawListBox turns the drawing process off prior to your application’s maintenance of lines. When the task is completed, DrawListBox turns the drawing process on and instantly displays all the visible lines.
An entire list box can be deleted by using DeleteListBox. If you ever want to clear the list box without deleting it, simply create a new (empty) list box using the identical list box number and co-ordinates.
When a window becomes inactive, any selected lines become deselected and the scroll bar is disabled. When the window is activated again, the selection(s) reappear and the scroll bar is enabled.
When a list box is no longer required, it is deleted by the DeleteListBox procedure, which releases the memory used by the list box. This is done automatically if a window is closed.
Fonts
`````
When a list box is created, the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) are remembered by the list box. The window’s settings can then be changed without affecting the list. Unlike regular list boxes, Tools Plus list boxes can each have a different font.
Handling List Boxes
```````````````````
Once a list box is created, Tools Plus performs all the processing required within the box and its scroll bar. When a window in inactive, Tools Plus deselects items in all list boxes on that window. When the window is activated again, all list boxes regain their original state as specified by your application. The PollSystem function is used to constantly inquire about any actions occurring in a list box.
Several types of events may indicate that your application has to perform some action. For example, you may want to enable or disable buttons based on whether a selection has been made in the list box. Or you may ignore all list box action and use GetListBoxLine to determine the selection only after an OK button is clicked. Though various interpretations can be implemented, please adhere to the Macintosh User Interface Guidelines as outlined in Inside Macintosh Volume I. In any case, PollSystem tells your application if any activity has occurred in a list box, or if a selection has been double clicked.
See the PollSystem function for details pertaining to list box events.
ListBox specifies the list box number (from 1 to 255) that is created in the current window. Once a list box is created, it is referenced by this list box number. If a list box has been previously created in the current window using the same number, it is replaced with a new (empty) list box as specified by the parameters in the NewListBox procedure (which is a good way to clear all of an existing list box’s lines). If the current window doesn’t belong to your application, or if no windows are open, NewListBox does nothing. In order to make a list box operate at its best, the list box’s height (difference between top and bottom) should be a multiple of its font’s height (font height can be determined by calling the GetFontInfo procedure and adding Ascent + Descent + Leading. The system font’s height is 16 pixels).
Left, top, right, and bottom define a rectangle in the current window’s local co-ordinates that determine the list box’s size and location in the window. These parameters can be seen as two corners; the upper left-hand corner (left,top) and the bottom right-hand corner (right,bottom). A 1-pixel wide outline is drawn as a frame for the list box just outside these co-ordinates. Also, a scroll bar is created along the entire length of the list box’s right side. The scroll bar is 16 pixels wide and is drawn outside the specified co-ordinates.
Selection Methods
`````````````````
BoxType specifies how lines are selected in the list. One constant rule is that blank lines cannot be selected. The default method used for selecting lines is detailed below (BoxType=0):
Option
``````
The Option key is always ignored, even when used in combination with other keys.
No Shift, or Command
````````````````````
Any click in the list box deselects previous selections and selects the line clicked by the user. If the mouse is moved while the mouse button is held down, only the line beneath the cursor is selected.
Shift
`````
If the Shift key is down before clicking the mouse, the selection is extended or shortened as if it were an expandable rectangle. When the mouse is first clicked, the selection is changed to include the line that was just clicked. If the mouse is dragged, the selection either extends or shortens to follow the mouse’s pointer.
Command
```````
If the Command key is down before clicking the mouse, lines are either selected or unselected, depending on the first clicked line. If the initial line was selected, it is deselected along with any other lines the mouse’s pointer passes over. If the initial line was not selected, it is selected along with any other lines the mouse’s pointer passes over. This is called “sense of first line.”
Several constants have been provided to let your application define the rules of selection. These constants can be used singularly or in combinations (such as lExtendDrag + lNoDisjoint). Note that the first letter is a lower case “l”, and not the number one (1).
lOnlyOne
````````
Only one line can be selected at a time. Any previous selection is deselected when a new line is clicked.
lExtendDrag
```````````
Selections are extended without using the Shift key. All lines dragged over by the mouse are selected. It works best when used in conjunction with lNoDisjoint, lNoExtend, lNoRect, and lUseSense.
lNoDisjoint
```````````
Multiple lines can be selected, but all lines are deselected when the mouse is clicked. This occurs even if the Shift or Command keys are held down, and prevents “disjointed” selections.
lNoExtend
`````````
The current selection is ignored. The mouse’s click defines an anchor point for the new Shift selection.
lNoRect
```````
Selections are not extended or shortened like “rectangles.” Instead, lines are selected as the mouse drags over them.
lUseSense
`````````
If the Shift key is pressed, “sense of first line” is in effect. This means if the initial line was selected, it is deselected along with any other line the mouse passes over. If the initial line was not selected, it is selected along with any other line the mouse passes over.
The following are three of the most common BoxType values your application will use, as well as an interesting though uncommon BoxType:
lOnlyOne
````````
Only one selection can be made at a time. Any previous selection is deselected. This is a Macintosh standard.
lNoExtend + lUseSense
`````````````````````
A click deselects previous selections. A Shift-Click selects a deselected line, or deselects a selected line. A Shift-Click can also be dragged to perform the same action across other lines. The “Font/DA Mover” uses this method.
A click deselects previous selections. Dragging the click selects lines along the drag. This is a good way to let the user select multiple lines that must be grouped together.
lExtendDrag + lNoExtend + lUseSense
```````````````````````````````````
A click selects a deselected line, or deselects a selected line. A click can be dragged to perform the same action across other lines. Shift is ignored. This selection method makes a list box behave as though it were a list of check boxes. Although this is a neat idea, it does not follow the Macintosh User Interface Guidelines.
Fonts
`````
When a list box is created, the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) are remembered by the list box. The window’s settings can be changed without affecting the list box. The list box’s font, size, and style cannot be changed without recreating the list box. We recommend that you use the system font (Chicago, 12 point) for list boxes, since this is the standard seen in almost all applications.
Also see: NewListBoxRect.
Note: Tools Plus makes no attempt to control the placement of list boxes
or to protect them once they have been created. It is the
programmer’s responsibility to ensure that list boxes are of
sufficient size to contain their lines, and that their placement
within the window is reasonable and does not conflict with other
objects. Furthermore, you should not allow the application’s text
and drawing processes to interfere with list boxes. Windows with
a “size box” should not allow list boxes to be obscured or hidden
by making the window too small.
CONST {List box selection methods }
lOnlyOne =-128; {only one selection at a time }
lExtendDrag= 64; {dragging without the Shift key }
lNoDisjoint= 32; {turn off multiple selections with click}
lNoExtend = 16; {don’t extend Shift clicks }
lNoRect = 8; {don’t expand selection like a rectangle}
lUseSense = 4; {Shift uses “sense of first cell” }
NewListBoxRect is identical to the NewListBox procedure, except that it accepts the Bounds rectangle in place of the individual left, top, right and bottom co-ordinates.
ListBox specifies the list box number (from 1 to 255) that is deleted from the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, DeleteListBox does nothing.
ListBox specifies the list box number (from 1 to 255) that is affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, SetListBoxText does nothing.
LineNum specifies the line number (from 1 to 32,767) that is affected in the specified list box. The line is created if it does not already exist. If necessary, blank lines are created between the last line in the list box and the new line being created. If the line already exists, the line’s text is simply replaced.
The Text parameter is the text that appears in the list box’s line. If the text’s width is too long to fit into the list box, it is be truncated and followed with an ellipsis (“…”).
Repeated calls of SetListBoxText should be bracketed by calls to DrawListBox. See the DrawListBox procedure for details.
ListBox specifies the list box number (from 1 to 255) that is queried in the current window.
LineNum specifies the line number (from 1 to 32,767) that is queried in the specified list box.
The Text variable is the text that appears in the list box’s specified line. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, or if LineNum does not exist in the specified list box, Text will return as a null string.
Search a list box for a line that is greater than or equal to the specified text.
pascal short SearchListBox (short ListBox, Str255 Text);
function SearchListBox(ListBox: INTEGER; Text: STRING): INTEGER;
ListBox specifies the list box number (from 1 to 255) that is queried in the current window.
Text is a string that is used to find a matching line.
The function searches all the lines in the specified list box for the string indicated by Text. If an exact match is found, the function’s value returns the line number containing the matching string. If a match is not found, the function returns the first line number that contains text that is greater than the specified Text. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, a value of zero (0) is returned.
This function is most useful if you want to create a list box with the lines in alphabetical order (such as fonts). Before your applications adds a line, call SearchListBox to determine where the line should be inserted. Using the returned value, call InsertListBoxLine to insert a blank line in the list box, then use SetListBoxText to set the blank line’s text. Keep in mind that the alphabetic comparison that is made between the list box’s lines and the string specified by Text differentiates between upper and lower case letters. Also, under systems older than System 7, the list box’s lines may have been truncated and suffixed by with an ellipsis (“…”) if they were too wide to fit in the list box.
ListBox specifies the list box number (from 1 to 255) that is affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, SetListBoxLine does nothing.
LineNum specifies the line number (from 1 to 32,767) that is affected in the specified list box. If the line number does not exist in the specified list box, SetListBoxLine does nothing.
SetIt specifies if the line is to be selected or deselected. The constants on and off can be used for this purpose.
The SetListBoxLine procedure should be used to set default lines within a list box immediately after it is created. Normally, you won’t have to use this routine because the user’s actions will select and deselect lines automatically.
Repeated calls to SetListBoxLine should be bracketed by calls to DrawListBox. See the DrawListBox procedure for details.
Determine if a specified line in a list box is selected or deselected.
pascal Boolean GetListBoxLine (short ListBox, short LineNum);
function GetListBoxLine(ListBox, LineNum: INTEGER): BOOLEAN;
ListBox specifies the list box number (from 1 to 255) that is queried in the current window.
LineNum specifies the line number (from 1 to 32,767) that is queried in the specified list box.
The function’s value returns as true if the line is selected, or false if the line is not selected. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, or if LineNum does not exist in the specified list box, the function’s value returns a false.
See the GetListBoxLines (ending with an “s”) function.
Find the first selected line in a list box, starting at a specified line number.
pascal short GetListBoxLines (short ListBox, short LineNum);
function GetListBoxLines(ListBox, LineNum: INTEGER): INTEGER;
ListBox specifies the list box number (from 1 to 255) that is queried in the current window.
LineNum specifies the line number (from 1 to 32,767) that is the first in a series to be queried in the specified list box.
The function’s value returns the line number of the first selected line starting at LineNum. If no selected lines were found, the function returns a value of zero (0). If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, or if LineNum does not exist in the specified list box, the function’s value returns a zero (0).
When multiple lines can be selected in a list box, GetListBoxLines is a good way to determine which lines are currently selected. Instead of checking each line individually, use GetListBoxLines with a LineNum of 1 to determine the first selected line. Add 1 to the resultant value to resume the search starting at the next LineNum. When GetListBoxLines returns a value of zero, you know you have reached the end of the list.
A second use for this function is to enable or disable a button depending on whether any items are selected in a list box. The “Open…” dialog box provides a good example. If a line (i.e. file name) is not selected in the list box, the Open button is disabled. As soon as a line is selected, the Open button is enabled. To do this, your application merely has to set up the correct default (or absence of one) in the list box, and correctly enable or disable a push button. When PollSystem informs your application that some activity has taken place in the list box, call GetListBoxLines with a LineNum of 1 to determine if any lines were selected. If GetListBoxLines returns a non-zero value, you know a selection has been made, otherwise, no selections have been made. Based on this conclusion, you could enable or disable the push button accordingly.
ListBox specifies the list box number (from 1 to 255) that is affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, InsertListBoxLine does nothing.
LineNum specifies the line number (from 1 to 32,767) that is the targeted destination for a blank line in the specified list box. The specified line number, and all the lines below it, are pushed down one line. If the line number does not exist in the specified list box, InsertListBoxLine does nothing.
Repeated calls to InsertListBoxLine should be bracketed by calls to DrawListBox. See the DrawListBox procedure for details.
ListBox specifies the list box number (from 1 to 255) that is affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, DeleteListBoxLine does nothing.
LineNum specifies the line number (from 1 to 32,767) that is deleted. The specified line number is deleted, and all the lines below it are moved up one line. If the line number does not exist in the specified list box, DeleteListBoxLine does nothing.
If you want to clear a line (i.e. clear the existing text and leave a blank line), use SetListBoxText and specify a null string ("\p" in C, or '' in Pascal).
Repeated calls to DeleteListBoxLine should be bracketed by calls to DrawListBox. See the DrawListBox procedure for details.
ListBox specifies the list box number (from 1 to 255) that is affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the list box does not exist in the current window, DrawListBox does nothing.
DrawIt specifies if the drawing is to be turned on or off. The constants on and off may be used. When list drawing is turned off, any changes made to the lines are not displayed although changes are invisibly accumulated. When list drawing is turned back on, the list box is drawn instantly with all its lines and selections displayed.
Because list boxes are “live,” the use of SetListBoxText, SetListBoxLine, InsertListBoxLine, and DeleteListBoxLine has an immediate affect on the appearance of your list box. This can become quite unsightly when adding one line at a time to a list box of any significant length. Whenever changes are going to be made to more than a single line, turn drawing off before making any changes. After all the changes are completed, turn list drawing back on.
